// Upload Repository 实现契约
// 基于 repository_api 接口定义，Pipeline Repository 实现层必须遵循的契约
//
// 注意：此文件是契约文档，不是可执行的 Dart 代码
// 实际实现时需要在 pipeline_repository 包中导入正确的依赖

// import 'package:repository_api/repository_api.dart';

/// Upload Repository 实现契约
/// 
/// 此文件定义了 Pipeline Repository 实现层必须遵循的接口契约。
/// 所有方法签名必须与 repository_api 中的 UploadRepository 接口完全一致。
/// 
/// 实现要求：
/// 1. 所有方法必须实现，不能抛出 UnimplementedError
/// 2. 异常处理必须符合 repository_api 的异常模型
/// 3. 数据转换必须通过 Mapper 进行，确保类型安全
/// 4. 双数据库操作必须协调一致
/// 5. 实时监听必须使用 Floor 的 watch 功能
abstract class UploadRepositoryContract {
  
  // ==================== 初始化与清理 ====================
  
  /// 初始化 Repository
  /// 
  /// 必须同时初始化持久化数据库和内存数据库
  /// 返回已初始化的 Repository 实例
  static Future<UploadRepository> initialize();
  
  /// 清理资源
  /// 
  /// 关闭数据库连接，释放资源
  Future<void> dispose();
  
  // ==================== 任务 CRUD 操作 ====================
  
  /// 创建单个任务
  /// 
  /// 将 Model 转换为 Entity 并保存到持久化数据库
  /// 返回包含生成 ID 的 Model
  Future<UploadTask> createTask(UploadTask task);
  
  /// 批量创建任务
  /// 
  /// 使用数据库事务保证原子性
  /// 要么全部成功，要么全部失败
  Future<List<UploadTask>> createTasks(List<UploadTask> tasks);
  
  /// 根据ID获取任务
  /// 
  /// 从持久化数据库读取 Entity 并转换为 Model
  /// 任务不存在时抛出 DataNotFoundException
  Future<UploadTask> getTaskById(String taskId);
  
  /// 获取所有任务
  /// 
  /// 返回所有任务的 Model 列表
  /// 支持分页查询（limit, offset）
  Future<List<UploadTask>> getAllTasks({int? limit, int? offset});
  
  /// 更新任务
  /// 
  /// 自动更新 updatedAt 字段为当前时间
  /// 任务不存在时抛出 DataNotFoundException
  Future<UploadTask> updateTask(UploadTask task);
  
  /// 删除任务
  /// 
  /// 同时清理内存数据库中的进度数据
  /// 任务不存在时抛出 DataNotFoundException
  Future<void> deleteTask(String taskId);
  
  /// 批量删除任务
  /// 
  /// 使用事务保证原子性
  /// 同时清理内存数据库中的相关进度数据
  Future<void> deleteTasks(List<String> taskIds);
  
  // ==================== 任务查询操作 ====================
  
  /// 根据用户ID获取任务
  /// 
  /// 使用 Floor DAO 查询并转换结果
  /// 支持分页查询
  Future<List<UploadTask>> getTasksByUserId(
    String userId, {
    int? limit,
    int? offset,
  });
  
  /// 根据状态获取任务
  /// 
  /// 直接使用相同的状态枚举，无需转换
  /// 支持分页查询
  Future<List<UploadTask>> getTasksByStatus(
    UploadTaskStatus status, {
    int? limit,
    int? offset,
  });
  
  /// 根据组ID获取任务
  /// 
  /// 获取指定组的所有任务
  Future<List<UploadTask>> getTasksByGroupId(String groupId);
  
  /// 根据用户和状态获取任务
  /// 
  /// 组合查询方法，同时满足用户和状态条件
  Future<List<UploadTask>> getTasksByUserIdAndStatus(
    String userId,
    UploadTaskStatus status,
  );
  
  /// 获取下一个待上传任务
  /// 
  /// 使用 SQL ORDER BY 按优先级降序、创建时间升序排序
  /// 没有待上传任务时返回 null
  Future<UploadTask?> getNextPendingTask();
  
  // ==================== 任务状态管理 ====================
  
  /// 更新任务状态
  /// 
  /// 直接使用相同的状态枚举，自动更新 updatedAt
  /// 任务不存在时抛出 DataNotFoundException
  Future<void> updateTaskStatus(String taskId, UploadTaskStatus status);
  
  /// 批量更新任务状态
  /// 
  /// 批量更新多个任务状态
  /// 使用事务保证原子性
  Future<void> updateTasksStatus(
    List<String> taskIds,
    UploadTaskStatus status,
  );
  
  /// 重置任务状态
  /// 
  /// 将指定状态的任务重置为待上传状态
  /// 返回受影响的记录数
  Future<int> resetTasksStatus(UploadTaskStatus fromStatus);
  
  /// 获取上传中的任务
  /// 
  /// 查询上传中状态的任务
  Future<List<UploadTask>> getUploadingTasks();
  
  // ==================== 进度管理 ====================
  
  /// 更新任务进度
  /// 
  /// 使用 INSERT OR REPLACE 语义保存到内存数据库
  /// 任务不存在时抛出 DataNotFoundException
  Future<void> updateProgress(UploadProgress progress);
  
  /// 根据任务ID获取进度
  /// 
  /// 从内存数据库读取并转换
  /// 进度不存在时返回 null
  Future<UploadProgress?> getProgressByTaskId(String taskId);
  
  /// 删除任务进度
  /// 
  /// 从内存数据库删除
  Future<void> deleteProgress(String taskId);
  
  /// 获取所有进度
  /// 
  /// 返回所有内存进度数据
  Future<List<UploadProgress>> getAllProgress();
  
  // ==================== 实时数据流监听 ====================
  
  /// 监听所有任务
  /// 
  /// 使用 Floor DAO 的 watch 功能，自动转换 Entity 流为 Model 流
  Stream<List<UploadTask>> watchAllTasks();
  
  /// 监听单个任务
  /// 
  /// 监听指定任务的变化
  /// 任务被删除时流发出 null
  Stream<UploadTask?> watchTaskById(String taskId);
  
  /// 监听用户任务
  /// 
  /// 监听指定用户的任务列表变化
  Stream<List<UploadTask>> watchTasksByUserId(String userId);
  
  /// 监听状态任务
  /// 
  /// 监听指定状态的任务变化
  Stream<List<UploadTask>> watchTasksByStatus(UploadTaskStatus status);
  
  /// 监听上传中任务
  /// 
  /// 便捷方法，监听上传中状态的任务
  Stream<List<UploadTask>> watchUploadingTasks();
  
  /// 监听待上传任务
  /// 
  /// 便捷方法，监听待上传状态的任务
  Stream<List<UploadTask>> watchPendingTasks();
  
  /// 监听所有进度
  /// 
  /// 监听内存数据库的进度变化
  Stream<List<UploadProgress>> watchAllProgress();
  
  /// 监听单个任务进度
  /// 
  /// 监听指定任务的进度变化
  /// 进度被删除时流发出 null
  Stream<UploadProgress?> watchProgressByTaskId(String taskId);
  
  // ==================== 统计查询 ====================
  
  /// 获取任务统计
  /// 
  /// 统计各状态的任务数量
  Future<TaskStatistics> getTaskStatistics();
  
  /// 获取用户任务统计
  /// 
  /// 统计指定用户的任务数量
  Future<Map<String, int>> getTaskCountByUserId(String userId);
  
  /// 获取组任务统计
  /// 
  /// 统计指定组的任务数量
  Future<Map<String, int>> getTaskCountByGroupId(String groupId);
}

/// 任务统计信息
class TaskStatistics {
  final int totalCount;
  final Map<UploadTaskStatus, int> statusCounts;
  final Map<UploadGroupType, int> groupTypeCounts;
  
  const TaskStatistics({
    required this.totalCount,
    required this.statusCounts,
    required this.groupTypeCounts,
  });
}

// ==================== 实现要求 ====================

/// 实现层必须遵循以下要求：
/// 
/// 1. 数据库架构：
///    - 持久化数据库：app_database，存储任务数据
///    - 内存数据库：app_mem_database，存储进度数据
///    - 双数据库协调：最佳努力提交 + 失败补偿
/// 
/// 2. 数据映射：
///    - 使用专门的 Mapper 类进行 Entity ↔ Model 转换
///    - 时间戳转换：Entity (int 毫秒) ↔ Model (DateTime)
///    - 枚举类型：直接使用 repository_api 中的定义
///    - 扩展字段：Entity 的扩展字段在 Mapper 中忽略
/// 
/// 3. 异常处理：
///    - DataNotFoundException：数据不存在
///    - DataValidationException：数据验证失败
///    - 底层 Floor 异常转换为 repository_api 异常类型
/// 
/// 4. 性能要求：
///    - 批量操作：100个任务/秒
///    - 数据流监听：<100ms 响应
///    - 高频进度更新：不影响主数据库性能
/// 
/// 5. 测试要求：
///    - 单元测试：Mapper、Repository 方法
///    - 集成测试：数据库操作、流监听
///    - 测试覆盖率：80%+
/// 
/// 6. 代码质量：
///    - 通过 dart analyze 静态分析
///    - 符合项目编码规范
///    - 完整的错误处理和日志记录
